[% 
  page.title = 'API' 
  page.tab = 'api'
  page.nocrumbs = 1 
%]

<p>The REST API is organised into the following functional areas.</p>

<ul id="contentTabs" class="contentTabs">
  <li><a href="#s1">Relations</a></li>
  <li><a href="#s2">Items</a></li>
  <li><a href="#s6">Functions</a></li>
[%# 
  <li><a href="#s3">Reports</a></li>
  <li><a href="#s4">System</a></li>
%]
  <li><a href="#s5">Workflow</a></li>
</ul>

<div id="s1" class="contentTab">
<h2 class="toprow">Relations</h2>
<p>
  A JSONMatch relation is a set of items.
</p>
<table class="api">
<tr><th class="api2">Method</th><th>HTTP</th><th>URI Schema</th><th>Parameters</th></tr>
<tr><td class="method"><a href="relations-list">list</a></td><td class="http">GET</td><td class="schema">/:user_id/relations</td><td class="params"><em>full</em></td></tr>
<tr><td class="method"><a href="relations-show">show</a></td><td class="http">GET</td><td class="schema">/:user_id/relations/:relation_id</td><td class="params"><em>full</em></td></tr>
<tr><td class="method"><a href="relations-exists">exists</a></td><td class="http">HEAD</td><td class="schema">/:user_id/relations/:relation_id</td><td class="params"></td></tr>
<tr><td class="method"><a href="relations-create">create</a></td><td class="http">POST</td><td class="schema">/:user_id/relations/:relation_id</td><td class="params"><em>description</em>, <em>mode</em>, <em>full</em></td></tr>
<tr><td class="method"><a href="relations-update">update</a></td><td class="http">PUT</td><td class="schema">/:user_id/relations/:relation_id</td><td class="params"><em>description</em>, <em>mode</em>, <em>full</em></td></tr>
<tr><td class="method"><a href="relations-destroy">destroy</a></td><td class="http">DELETE</td><td class="schema">/:user_id/relations/:relation_id</td><td class="params"><em>full</em></td></tr>
</table>
</div>

<div id="s2" class="contentTab">
<h2 class="toprow">Items</h2>
<p>
  An item is a JSON array, object or scalar.
</p>
<table class="api">
<tr><th class="api2">Method</th><th>HTTP</th><th>URI Schema</th><th>Parameters</th></tr>
<tr><td class="method"><a href="relation-items-count">count</a></td><td class="http">GET</td><td class="schema">/:user_id/relations/:relation_id/count</td><td class="params"></td></tr>
<tr><td class="method"><a href="relation-items-creating">creating</a></td><td class="http">HEAD</td><td class="schema">/:user_id/relations/:relation_id/creating</td><td class="params"></td></tr>
<tr><td class="method"><a href="relation-items-index">index</a></td><td class="http">GET</td><td class="schema">/:user_id/relations/:relation_id/index</td><td class="params"><em>page</em>, <em>count</em></td></tr>
<tr><td class="method"><a href="relation-items-list">list</a></td><td class="http">GET</td><td class="schema">/:user_id/relations/:relation_id/items</td><td class="params"><em>page</em>, <em>count</em>, <em>full</em></td></tr>
<tr><td class="method"><a href="relation-items-show">show</a></td><td class="http">GET</td><td class="schema">/:user_id/relations/:relation_id/items/:item_id</td><td class="params"><em>full</em></td></tr>
<tr><td class="method"><a href="relation-items-exists">exists</a></td><td class="http">HEAD</td><td class="schema">/:user_id/relations/:relation_id/items/:item_id</td><td class="params"></td></tr>
<tr><td class="method"><a href="relation-items-create-multiple">create</a></td><td class="http">POST</td><td class="schema">/:user_id/relations/:relation_id/items</td><td class="params">items_list, <em>full</em></td></tr>
<tr><td class="method"><a href="relation-items-create">create</a></td><td class="http">POST</td><td class="schema">/:user_id/relations/:relation_id/items/:item_id</td><td class="params">text, <em>description</em>, <em>full</em></td></tr>
<tr><td class="method"><a href="relation-items-update-multiple">update</a></td><td class="http">PUT</td><td class="schema">/:user_id/relations/:relation_id/items</td><td class="params">items_list, <em>full</em></td></tr>
<tr><td class="method"><a href="relation-items-update">update</a></td><td class="http">PUT</td><td class="schema">/:user_id/relations/:relation_id/items/:item_id</td><td class="params"><em>text</em>, <em>description</em>, <em>full</em></td></tr>
<tr><td class="method"><a href="relation-items-destroy-all">destroy</a></td><td class="http">DELETE</td><td class="schema">/:user_id/relations/:relation_id/items</td><td class="params"><em>full</em></td></tr>
<tr><td class="method"><a href="relation-items-destroy">destroy</a></td><td class="http">DELETE</td><td class="schema">/:user_id/relations/:relation_id/items/:item_id</td><td class="params"><em>full</em></td></tr>
</table>
</div>

[%#
<div id="s3" class="contentTab">
<h2 class="toprow">Reports</h2>
<p>
  For convenience, JSONMatch provides report generation to present data created in profiles and matches relations in
  human-centric formats, such as HTML, rather than machine-centric formats, such as XML, JSON, etc. 
  Reports are generated as files in <em>report relations</em>, which have the same creation and access control
  methods supported by the other relation types in JSONMatch's REST API.
  Unlike other JSONMatch relations, <em>report relations</em> do not contain API addressable data items; instead they contain files
  which may be viewed or downloaded as ordinary web pages.
</p>

<h3 class="api">Reports Folders</h3>
<p>
  JSONMatch <em>reports relations</em> provide an API controllable way of generating HTML reports detailing specific profiles and matches.
  A <em>report relation</em> may be published to the web with either public or restricted access. Alternatively, <em>reports relations</em>
  may be downloaded as a zip archive for distribution or publishing to third-party web servers or content management systems.
</p>
<table class="api">
<tr><th class="api2">Method</th><th>HTTP</th><th>URI Schema</th><th>Parameters</th></tr>
<tr><td class="method"><a href="reports-list">list</a></td><td class="http">GET</td><td class="schema">/:user_id/reports</td><td class="params"></td></tr>
<tr><td class="method"><a href="reports-show">show</a></td><td class="http">GET</td><td class="schema">/:user_id/reports/:relation_id.:format</td><td class="params"></td></tr>
<tr><td class="method"><a href="reports-exists">exists</a></td><td class="http">HEAD</td><td class="schema">/:user_id/reports/:relation_id</td><td class="params"></td></tr>
<tr><td class="method"><a href="reports-create-profiles">create</a></td><td class="http">POST</td><td class="schema">/:user_id/reports/:relation_id/profiles/:profiles_id</td><td class="params"><em>description</em>, <em>mode</em>, <em>type</em></td></tr>
<tr><td class="method"><a href="reports-create-matches">create</a></td><td class="http">POST</td><td class="schema">/:user_id/reports/:relation_id/matches/:matches_id</td><td class="params"><em>description</em>, <em>mode</em>, <em>type</em></td></tr>
<!--
<tr><td class="method"><a href="reports-update">update</a></td><td class="http">PUT</td><td class="schema">/:user_id/reports/:relation_id/profiles/:profiles_id</td><td class="params"><em>description</em>, <em>mode</em></td></tr>
<tr><td class="method"></td><td class="http">PUT</td><td class="schema">/:user_id/reports/:relation_id/matches/:matches_id</td><td class="params"><em>description</em>, <em>mode</em></td></tr>
-->
<tr><td class="method"><a href="reports-destroy">destroy</a></td><td class="http">DELETE</td><td class="schema">/:user_id/reports/:relation_id</td><td class="params"></td></tr>
</table>

<h3 class="api">Report Files</h3>
<p>
  Each <em>reports relation</em> contains report files generated when the relation was created or last updated.
  The exact names and types of files generated depend on the report type.
  However, there will always be an <code>index.html</code> file representing the home page of the report,
  and an <code>index.zip</code> file which contains all the files in the report as a downloadable archive.
  If the <em>report relations</em> is set to <code>public</code> then it functions as a self-contained website
  which may be publicised via its URL or linked to in the normal way from other web pages.
</p>
<table class="api">
<tr><th class="api2">Method</th><th>HTTP</th><th>URI Schema</th><th>Parameters</th></tr>
<tr><td class="method"><a href="report-homepage">report homepage</a></td><td class="http">GET</td><td class="schema">/:user_id/reports/:relation_id[.html]</td><td class="params"></td></tr>
<tr><td class="method"></td><td class="http">GET</td><td class="schema">/:user_id/reports/:relation_id/index[.html]</td><td class="params"></td></tr>
<tr><td class="method"><a href="report-download">report download</a></td><td class="http">GET</td><td class="schema">/:user_id/reports/:relation_id.zip</td><td class="params"></td></tr>
<tr><td class="method"></td><td class="http">GET</td><td class="schema">/:user_id/reports/:relation_id/index.zip</td><td class="params"></td></tr>
</table>
</div>

<div id="s4" class="contentTab">
<h2 class="toprow">System</h2>
<p>
  System methods provide functionality that does not fit into the relations and items model employed by the rest of the API.
</p>
<p>
  The status/test methods can be used to check, for the service overall or for an individual user, that the REST API is up and running as normal.
</p>
<table class="api">
<tr><th class="api2">Method</th><th>HTTP</th><th>URI Schema</th><th>Parameters</th></tr>
<tr><td class="method"><a href="status-test">status test</a></td><td class="http">GET</td><td class="schema">/status/test</td><td class="params"></td></tr>
<tr><td class="method"><a href="status-test">status test</a></td><td class="http">POST</td><td class="schema">/status/test/:user_id</td><td class="params"></td></tr>
</table>
</div>
%]

<div id="s5" class="contentTab">
<h2 class="toprow">Workflow</h2>
<p>JSONMatch has a minimalist <em>workflow engine</em> that enables the creation and batch execution of sequences of API method calls specified in a simple workflow language (relationed on the create method below). Creating a workflow adds its sequence of commands to the workflow engine's <em>enactment</em> queue, eventually resulting in each method call in the workflow being executed one after the other. Using workflows greatly simplifies the use of the JSONMatch API by enabling this batch execution of method calls without the need for multiple consecutive HTTP requests from the client program. All the client program needs to do is wait for the workflow to complete, which can be detected by periodically issuing the <code>enacting</code> method. The downside is that workflows run as background tasks on the server and will not execute as quickly as if the sequence of methods were issues as multiple HTTP requests by the client. However, for non-interactive applications, this is the simplest way of using JSONMatch.</p>
<table class="api">
<tr><th class="api2">Method</th><th>HTTP</th><th>URI Schema</th><th>Parameters</th></tr>
<tr><td class="method"><a href="workflow-create">create</a></td><td class="http">POST</td><td class="schema">/:user_id/workflow/:workflow_id</td><td class="params">commands</td></tr>
<tr><td class="method"><a href="workflow-enacting">enacting</a></td><td class="http">HEAD</td><td class="schema">/:user_id/workflow/:workflow_id</td><td class="params"></td></tr>
<tr><td class="method"><a href="workflow-destroy">destroy</a></td><td class="http">DELETE</td><td class="schema">/:user_id/workflow/:workflow_id</td><td class="params"></td></tr>
</table>
</div>


<div id="s6" class="contentTab">
<h2 class="toprow">Functions</h2>
<p>JSONMatch allows functions to be embedded in the JSON templates for relations and items passed to transformations.</p>
<pre>
["namespace:function", arg1,...,argN]
</pre>
<table class="api">
<tr><th></th><th class="api2">Function</th><th>&nbsp;Description</th></tr>

<tr><th class="fn1" rowspan="5">Meta</th><td class="fn2"><a href="funtion-">apply</a></td><td class="fn3">Apply higher-order JSON template to each element of an array.</td></tr>
<tr><td class="fn2"><a href="funtion-">restrict</a></td><td class="fn3">Select values in an array that satisfy a predicate.</td></tr>
<tr><td class="fn2"><a href="funtion-">generate</a></td><td class="fn3">As <i>apply</i> but outputs results as new relation items.</td></tr>
<tr><td class="fn2"><a href="funtion-">project</a></td><td class="fn3">Subpart/s of a value identified by a JSONPath expression.</td></tr>
<tr><td class="fn2"><a href="funtion-">types</a></td><td class="fn3">Detect types of all subparts of a JSON value.</td></tr>
<th colspan="3"></th>

<tr><th class="fn1" rowspan="4">Web</th><td class="fn2"><a href="funtion-">http_get</a></td><td class="fn3">Fetches text of web page; or REST call.</td></tr>
<tr><td class="fn2"><a href="funtion-">http_post</a></td><td class="fn3">Submits web form; or REST call.</td></tr>
<tr><td class="fn2"><a href="funtion-">register</a></td><td class="fn3">Register external REST functions.</td></tr>
<tr><td class="fn2"><a href="funtion-">rpc</a></td><td class="fn3">Remote procedure call to registered external REST functions.</td></tr>
<th colspan="3"></th>

<tr><th class="fn1" rowspan="3">Time</th><td class="fn2"><a href="funtion-">time</a></td><td class="fn3">Floating seconds since Epoch (using millisecond accuracy).</td></tr>
<tr><td class="fn2"><a href="funtion-">interval</a></td><td class="fn3">Floating seconds between two times.</td></tr>
<tr><td class="fn2"><a href="funtion-">timestamp</a></td><td class="fn3">Time when the current transformation started.</td></tr>
<th colspan="3"></th>

<tr><th class="fn1" rowspan="12">Sets</th><td class="fn2"><a href="funtion-">set</a></td><td class="fn3">Constructs a key-boolean set from an array of keys.</td></tr>
<tr><td class="fn2"><a href="funtion-">set_cardinality</a></td><td class="fn3">Cardinality of N key-boolean sets as the number of unique keys.</td></tr>
<tr><td class="fn2"><a href="funtion-">set_union</a></td><td class="fn3">Union of N key-boolean sets as a key-boolean set.</td></tr>
<tr><td class="fn2"><a href="funtion-">multiset</a></td><td class="fn3">Constructs a key-multiplicity set from an array of keys.</td></tr>
<tr><td class="fn2"><a href="funtion-">multiset_cardinality</a></td><td class="fn3">Cardinality of N key-multiplicity sets as the sum of multiplicities.</td></tr>
<tr><td class="fn2"><a href="funtion-">multiset_increment</a></td><td class="fn3">Increments a key-count set for each key in N multisets/arrays.</td></tr>
<tr><td class="fn2"><a href="funtion-">multiset_union</a></td><td class="fn3">Union of N key-multiplicity sets as a key-multiplicitysum set.</td></tr>
<tr><td class="fn2"><a href="funtion-">object</a></td><td class="fn3">Constructs a key-value set from [key,value,key,value,...] array.</td></tr>
<tr><td class="fn2"><a href="funtion-">object_cardinality</a></td><td class="fn3">Cardinality of a key-value set as the number of keys.</td></tr>
<tr><td class="fn2"><a href="funtion-">object_keys</a></td><td class="fn3">Keys of a key-value set as an array of keys.</td></tr>
<tr><td class="fn2"><a href="funtion-">object_values</a></td><td class="fn3">Values of a key-value set as an array of values.</td></tr>
<tr><td class="fn2"><a href="funtion-">object_union</a></td><td class="fn3">Union of N key-value sets as a key-[value,value,...] set.</td></tr>
<th colspan="3"></th>

<tr><th class="fn1" rowspan="5">Arrays</th><td class="fn2"><a href="funtion-">push</a></td><td class="fn3">Appends a value to the end of an array.</td></tr>
<tr><td class="fn2"><a href="funtion-">append</a></td><td class="fn3">Appends an array of values to the end of an array.</td></tr>
<tr><td class="fn2"><a href="funtion-">size</a></td><td class="fn3">Number of elements in an array.</td></tr>
<tr><td class="fn2"><a href="funtion-">sort</a></td><td class="fn3">Sort values in an array, possibly on a specified subpart.</td></tr>
<tr><td class="fn2"><a href="funtion-">limit</a></td><td class="fn3">Truncate array to keep first N values.</td></tr>
<th colspan="3"></th>

<tr><th class="fn1" rowspan="10">String</th><td class="fn2"><a href="funtion-">extract</a></td><td class="fn3">Substring matching a regular expression.</td></tr>
<tr><td class="fn2"><a href="funtion-">remove_html</a></td><td class="fn3">Strips HTML mark-up from a string.</td></tr>
<tr><td class="fn2"><a href="funtion-">downcase</a></td><td class="fn3">Converts a string to lower case.</td></tr>
<tr><td class="fn2"><a href="funtion-">upcase</a></td><td class="fn3">Converts a string to upper case.</td></tr>
<tr><td class="fn2"><a href="funtion-">length</a></td><td class="fn3">Length of string.</td></tr>
<tr><td class="fn2"><a href="funtion-">concat</a></td><td class="fn3">Concatenate array of strings (with optional separator).</td></tr>
<tr><td class="fn2"><a href="funtion-">strip</a></td><td class="fn3">Strip specified characters from string.</td></tr>
<tr><td class="fn2"><a href="funtion-">latinise</a></td><td class="fn3">Replace diacritics with latin character/s.</td></tr>
<tr><td class="fn2"><a href="funtion-">normalise_whitespace</a></td><td class="fn3">Replace whitespace sequences by a single space.</td></tr>
<tr><td class="fn2"><a href="funtion-">split</a></td><td class="fn3">Splits a string into a list of words.</td></tr>
<th colspan="3"></th>

<tr><th class="fn1" rowspan="10">Text</th><td class="fn2"><a href="funtion-">entities</a></td><td class="fn3">Recognises names of people, places, etc.</td></tr>
<tr><td class="fn2"><a href="funtion-">stem</a></td><td class="fn3">Replaces words with their Porter stem.</td></tr>
<tr><td class="fn2"><a href="funtion-">ngrams</a></td><td class="fn3">Returns n-grams from a list of words.</td></tr>
<tr><td class="fn2"><a href="funtion-">pgrams</a></td><td class="fn3">Returns p-spectrum of a list of words.</td></tr>
<tr><td class="fn2"><a href="funtion-">prefixes</a></td><td class="fn3">Counts left substrings of a list of words.</td></tr>
<tr><td class="fn2"><a href="funtion-">exclude_words</a></td><td class="fn3">Removes supplied ‘stopwords’ from list.</td></tr>
<tr><td class="fn2"><a href="funtion-">include_words</a></td><td class="fn3">Restricts words to supplied vocabulary.</td></tr>
<tr><td class="fn2"><a href="funtion-">replace_words</a></td><td class="fn3">Substitutes words using supplied mapping.</td></tr>
<tr><td class="fn2"><a href="funtion-">min_length</a></td><td class="fn3">Deletes words below specified length.</td></tr>
<tr><td class="fn2"><a href="funtion-">stopwords</a></td><td class="fn3">Set of common English words.</td></tr>
<th colspan="3"></th>

<tr><th class="fn1" rowspan="8">Comparison</th><td class="fn2"><a href="funtion-">if</a></td><td class="fn3">If argument1 then argument2 else argument3.</td></tr>
<tr><td class="fn2"><a href="funtion-">eq</a></td><td class="fn3">True if arguments are equal.</td></tr>
<tr><td class="fn2"><a href="funtion-">gt</a></td><td class="fn3">True if argument1 &gt; argument2.</td></tr>
<tr><td class="fn2"><a href="funtion-">lt</a></td><td class="fn3">True if argument1 &lt; argument2.</td></tr>
<tr><td class="fn2"><a href="funtion-">not</a></td><td class="fn3">True if argument is false.</td></tr>
<tr><td class="fn2"><a href="funtion-">tfidf</a></td><td class="fn3">Calculates TF-IDF for a multiset of words.</td></tr>
<tr><td class="fn2"><a href="funtion-">cosine</a></td><td class="fn3">Cosine similarity of term-weight vectors.</td></tr>
<tr><td class="fn2"><a href="funtion-">kernel</a></td><td class="fn3">Kernel (as a distance) on JSON values.</td></tr>
<th colspan="3"></th>

</table>
</div>


